QuickTime 3 Reference

| Previous | Chapter Contents | Chapter Top | Next |

The Effect Component Interface

Effect components, as with all other types of QuickTime components, must implement a defined set of functions. To ease the component development process, the GenericEffect component is provided for you. This component implements many of the "housekeeping" functions that all components must perform. In most cases, these default implementations are appropriate for your effect, and you simply delegate these functions to the generic effect component. In the rare instances when you need to provide your own implementations of one of these basic functions, you can override the generic version and provide your own implementation.

By delegating many of the functions to the generic effect, you not only decrease the number of functions you must implement, you also produce a smaller effect component, because common code is stored only once, in the generic effect.

The framework code provided in the dimmer effect sample shows how to delegate interface functions to the generic effect component.

The remaining functions that your component must provide implementations for are:

• Open opens a connection between the client software and your component.
• Close closes the connection between the client and your component.
• Version returns the version number of your component.
• EffectSetup is called once before a sequence of frames are rendered. This gives your effect the chance to set up variables that will alter their value during the execution of a sequence of frames.
• EffectBegin is called once before a frame is rendered. Your component can safely perform operations that move memory when this function is called.
• EffectRenderFrame is called to render a frame. Because this function can be called asynchronously, it is not safe to perform operations that may move memory during this call.
• EffectCancel cancels the rendering of a frame. If your component supports asynchronous operation, this function can be called while a frame is being rendered.
• GetParameterListHandle returns a parameter description atom container, as described in the section "Supplying Parameter Description Information" .
• GetCodecInfo returns information to the codec manager about the capabilities of your component.
• EffectGetSpeed returns the approximate number of frames per second that your effect is capable of transforming.

These functions can be categorized into four groups. The Open and Close functions deal with maintaining a connection between your component and client software. In most cases, you will not need to alter the implementations of these functions from the sample code provided by Apple.

The Version , GetParameterListHandle , GetCodecInfo and EffectGetSpeed functions return information about your component. The most important of these functions is GetParameterListHandle , which returns a description of the parameters that your effect can take. See "Supplying Parameter Description Information" for more details of this what this function should do.

The EffectSetup function is called immediately before your component is required to render a sequence of frames. On entry, the function contains a description of the sequence that is about to be rendered. Most importantly, it describes the bit depth and pixel format of the sources that your component has to deal with. Your Setup function can then verify that your component can handle these formats. If it cannot, EffectSetup should return the "closest" bit depth and pixel format combination that it can handle, and QuickTime will generate versions of the sources and destination in the requested format. This ensures that your effect only ever handles source and destination buffers in a format it understands. See "The EffectRenderFrame Function" for more details.

The most significant group contains the EffectBegin , EffectRenderFrame and EffectCancel functions. These functions contain the implementation of your effect algorithm. In most cases, you will not need to alter the implementations of the EffectCancel function from the sample code provided by Apple. The implementation of EffectBegin and RenderFrame functions is covered in "Implementing EffectBegin and EffectRenderFrame Functions" .

Full details of the interface functions your component must supply are given in "Component-Defined Functions" .

| Previous | Chapter Contents | Chapter Top | Next |